Object Oriented Programming with States [Version 1.0a] Since the first version has been released one year ago (this version was hardly working) number of significant improvements have been made to the tools supporting the 'Object Oriented Programming with States' paradigm. The version 1.0a is the first version to implement almost all the concepts of the programmation with states (as well as some 'extra goodies'), making it the ideal support of quality programming for C++ developers. More important, the version 1.0a is the first version robust enough to be 'whidely' used (for initiation purposes). Any comments and remarks concerning the tools, the documentation or the examples are welcomme. You can contact me at the following addresses: - "H.Lecoeuche@uk22p.bull.co.uk" - "hutch@ifhpserv.insa-lyon.fr" Table of content: 1 - Presentation of "Object Oriented Programming with States" paradigm 2 - The OOPS Toolset 3 - Content of package & installation ------------ 4 - The two demo examples 5 - The speed test 6 - Future of the OOPS Toolset Copyright notice: Copyright (c) 1991-1995 Hugues Lecoeuche Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice, author statement and this permission notice appear in all copies of this software and related documentation. THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. /1/ - Presentation of "Object Oriented Programming with States" --------------------------------------------------------- Programming by states (or with states) makes it possible to directly exploit, at the application source code level, the information present in the dynamic models produced during the analisys and design stages. Dynamic models, expressed in terms of state/transition diagrams are translated into state declarations inserted in the class interfaces. The declaration of the states makes use of a syntactical extention of the underlying object oriented programming language. In the case of the C++ language, this extention introduces 14 new key words (not all of them being directly related with the states declarations). A pre-processor transforms the state declarations into control code that is inserted into the application initial code (i.e. the code written by the developper). The control consists in checking that: - at the beginning of each method execution the object current state effectively allows to execute the method, - at the end of each method execution, the object current state effectively coresponds to the expected one (state transition validation). The interrest of this approach is that it does not require any extra effort from the developper in order to introduce controls that automatically ensure that, at run time, objects behave as expected (i.e. their effective behaviour is compliant with the behavior described in the state/transition diagrams of their classes). The main advantage of the state notion used in this approach is to perfectly fit into the inheritance hierarchy of the classes (i.e. to support inheritance between classes). This hability makes it possible to exploit in sub-classes the behavior described in the ancestor classes. /2/ - The "Object Oriented Programming with States" supporting Toolset ---------------------------------------------------------------- The version 1.0a of the tools supporting the "programming with states" paradigm only contains the translation tools (i.e. tools that translate state declarations into control code). Graphical tools able to translate state/transition diagrams into state declarations are still in development stage. Files containing enriched C++ code are distinguished from files containing native C++ code on a name extension basis. The extensions used by the tools to differentiate the files may be changed in the file 'CHECKER.CFG'. By default, the following extension are used: - ".EHP" for files containing the declaration of classes declaring states, - ".ECP" for files containing the definition of classes declaring states, The translation tools (CHECKER.EXE and EPURE.EXE) are called using the command: "CHECKER.EXE " To obtain some help on the diferent options available just enter: "CHECKER.EXE" (without any option or file name). The translation tools of the version 1.0a support: - state abandon, - state redefinition, - abstract states, - incompatibility declaration between states, - classes that do not declare states inheriting from classes declaring states, - multiple inheritance between classes declaring states, - parametrized translation to optimise execution time, - debug mode translation, - state entry debugging massages, /new/ - a code generation adapted to the target compiler (for example the hability of the compiler to support exceptions), - a code generation adapted to the user constraints (increasing object size vs numerous compile time warnings), - parametrized file name extensions for translated and generated files, - pre/post conditions for methods (even though this is not directly related to the state notion pre/post conditions are known to improve code reliability), /new/ - the hability to 'freeze' methods (contrary of 'virtual' (even though this is not directly related to the state notion this feature eases the developpment of robust class libraries). /new/ /3/ - Content of the package & installation ------------------------------------- The package contains: - the source files of two complete example of 'state programmation', - the version 1.0a of the translating tools, - a presentation document of the OOPS Toolset (practical and theoretical), - a guided tour and a demonstration program under windows, Installation: A) From the 'Net': If you have imported the file 'OOPSV10A.ZIP', unzip it in any directory you like (for example the 'TEMP' directory of your hard drive) and run the 'SETUP.EXE' installation procedure from within Windows. B) From a loppy: Run the 'SETUP.EXE' installation procedure from within Windows. The installation procedure allows to choose the target directory as well as 'a la carte' installation of the different provided elements. In case of a complete installation, 7 sub-directories are created under the main target directory: - DEMODOC that contains the source files of a very simple example, - DEMOLIFT that contains the source files of a quite complicated example, - DEMOWIN that contains the source files and the windows demonstration program, - OOPSTOOL that contains the binary files of the translation tools, - OOPSTOUR that contains the documentation that comes with the demo disk. (one 'WinWord6' document presenting the concepts and the details of the examples ; one 'PowerPoint4' document ment to be an "OOPS guided tour"), - OOPSLIB that contains the OOPS library required to compile the translated source code, - LIB that contains libraries used by the compiler, - INCLUDE that contains include files used by the compiler, Remarks: - the complete installation of the OOPS Toolset requires 2,5 Mo. - the installation does NOT modify any system file. - the installation does copy the dumy program named 'OOPSICO.EXE' into the 'Windows\System' directory of the computer. This program is only intended to store the icons used in the 'OOPS' group. It can be deleted at any time without any problem (only the icons will not be accessible any more). /4/ - The examples ------------ Two examples are provided with the OOPS Toolset in order to illustrate the use of the 'Programming with State' paradigm: - DEMODOC : Simple example (stored in the DEMODOC directory), - DEMOLIFT : More complicated example (stored in the DEMOLIFT directory). For both examples, all the files required to translate/compile the example are present in the related directory. This file are of 4 different nature: <1> The source files of the application, - the files with extension ".EHP" and ".ECP" - may be some other files (depending on the example) <2> The configuration file used for the translation: - 'STATE.CFG' <3> The project files used by the compiler: - 'DEMODOC.PRJ' / 'DEMOLIFT.PRJ' - 'DEMODOC.DSK' / 'DEMOLIFT.DSK' <4> The command files used to automatize some tasks: - 'CLEAN.BAT' to delete files generated by the translation process, - 'GETTOOLS.BAT' to copy the tools in the directory containing the source files to be translated, - 'GETLIB.BAT' to copy the "programming by state" compile library in the directory containing the source files to be translated, - 'TRADUIRE.BAT' to start the translation process. WARNING: In order to compile the examples, you should have a C++ compiler able to generate DOS code. You will have to adapt the 'makefile' files provided with each example. You may also have to customize the files 'CHECKER.CFG' and 'STATE.CFG' in order to make them compliant with the requirements of you C++ compiler. A) The 'STATE.CFG' file: /* *************************************************************** */ /* configuration file for the controls based on state descriptions */ /* *************************************************************** */ /* --------------------------------------------------------------- */ /* List of the supported operating systems. */ /* --------------------------------------------------------------- */ #define STATE_DOS 1 #define STATE_WINDOWS 2 /* --------------------------------------------------------------- */ /* Definition of the current operating system. */ /* --------------------------------------------------------------- */ #define STATE_SYSTEME STATE_DOS <<== MANDATORY FOR THE PROVIDED EXAMPLES /* --------------------------------------------------------------- */ /* List of the supported family of compilers. */ /* --------------------------------------------------------------- */ #define STATE_BORLAND 1 #define STATE_MICROSOFT 2 /* --------------------------------------------------------------- */ /* Definition of the current compiler. */ /* --------------------------------------------------------------- */ #define STATE_COMPILER STATE_XXXX <<== TO BE ADAPTED TO YOUR NEEDS /* --------------------------------------------------------------- */ /* STATE_DEBUG controls the introduction of 'debug' functions. */ /* --------------------------------------------------------------- */ #define STATE_DEBUG <<== may be removed /* --------------------------------------------------------------- */ /* STATE_TRACE controls the introduction of 'traces' in the code. */ /* --------------------------------------------------------------- */ /* #define STATE_TRACE */ <<== only use in case of problems /* --------------------------------------------------------------- */ /* The STATE_LIGHT option should be set to 1 only if the */ /* translation option used for ALL the files of the application is */ /* "-tl" or "-TL". */ /* --------------------------------------------------------------- */ #define STATE_LIGHT 0 <<== advanced option !!! /* --------------------------------------------------------------- */ /* STATE_USE_EXCEPT controls the use of exceptions in the */ /* generated code. */ /* --------------------------------------------------------------- */ #define STATE_USE_EXCEPT 1 <<== 0 or 1 depending on your compiler <<== ability to support exceptions /* --------------------------------------------------------------- */ /* STATE_OLD_COMPILER for very old compilers. */ /* --------------------------------------------------------------- */ #define STATE_OLD_COMPILER 0 <<== 0 or 1 depending of the age of <<== your compiler (try 0 first) /* --------------------------------------------------------------- */ /* The STATE_STATIC_IN_INLINE is an advanced option !! */ /* When set to 0 it prevents the introduction of static variables */ /* into inline methods. The translation does then increase the */ /* size of the objects as the variables are introduced as a */ /* private object variables. */ /* When set to 1 it allows the introduction of static variables */ /* into inline methods. The translation does then induce lot of */ /* warning messages at compile time. */ /* --------------------------------------------------------------- */ #define STATE_STATIC_IN_INLINE 0 <<== 0 or 1 (tru 0 first) B) the 'CHECKER.CFG' file: The tools CHECKER.EXE and EPURE.EXE read and generate files whith extension name that may be parametrized by the user. The file containing the extensions to be used by the tools is named 'CHECKER.CFG'. It is located in the 'OOPSTOOL' sub-directory. The information provided by the file 'CHECKER.CFG' is used by the tools in order to differenciate the input files (files containing enriched source code). It is also used by the tools to generate files whose names are compliants with the compiler used to compile the generated files. MAIN_ROOT_NAME="main"<<== root of the name of files containing free functions. STATE_DCL_EXT="ehp" <<== declaration of classes with states (enriched code) STATE_DEF_EXT="ecp" <<== definition of classes with states (enriched code) CPP_DCL_EXT="hpp" <<== normal declaration of classes (native code) CPP_DEF_EXT="cpp" <<== normal definition of classes (native code) NOT_FILE_EXT="not" <<== extention of files that should NOT be read TMP_FILE_EXT="tmp" <<== extention of temporary files COD_FILE_EXT="cod" <<== extention of constant files DANGER: DO NOT CHANGE THIS LAST EXTENSION!!! /* ------------------------------------------------------------------- */ /* WARNING: */ /* If the 'CPP_DCL_EXT' and 'CPP_DEF_EXT' have to be changed to comply */ /* with your C++ compiler do not forget to: */ /* - rename properly the files of the 'OOPS library' */ /* - change the "#include" statements in the files of the 'OOPS library*/ /* ------------------------------------------------------------------- */ Remark: As the files 'CLEAN.BAT' and 'TRANSLATE.BAT' use the extensions of the generated files it is better update these files and the 'CHECKER.CFG' file at the same time. The DEMODOC example =================== ** Presentation ** This example simulates the behavior of a book used in a library. The user acts through a command menu proposing the 8 folowing options: - 1 : Register (used to give a reference to the book) - 2 : Consulting (used to consult the book when it is on shelves) - 3 : Damage (used to signal that the book is damaged and need to be rebounded) - 4 : Repared (used to signalthe the book has been rebounded) - 5 : Borrow (used to signal the the book is borrowed by a library member) - 6 : Renew (used to renew the borrowing) - 7 : Restitute (used to signal a borrowed book has been returned) - 8 : Quit (no comments) The behavior of the book is such that it can not be used when it is to be rebound. It neither can be consulted when it is borrowed. The way the programm is translated is such that the 'Document' class (the base classe of the example class hierarchy is translated in debug mode. This is the reason why messages like are some time displayed. The 'damaged' state (defined in the 'RepearableDocument' class is enriched with the debug option 'toSignal'. This is the reason why a message is displayed each time the object current state is 'damaged'. For more accurate information concerning the classes used in this example please refer to the documentation provided with the 'Demo Disk'. ** The example source files ** The DEMODOC example source file are: - the files with extension ".EHP" and ".ECP", ** Translation/compilation of the example ** The translation/compilation of the example is completely automated by the file 'DEMODOC.BAT' you can find in the main installation target directory (provided you have properly updated the 'makefile' file). The translation can also be done manually by going through the following stages: - As the translation requiers the translating tools to be in the same directory than the files to be translated the tools may be copied in this directory by running the 'GetTools.BAT' file. - The example translation only works on the files having ".EHP" and ".ECP" as extension. The translation may be started by running the file 'TRANSLATE.BAT'. - The compilation of the example requires the "programming by state" library to be present in the same directory than the translated files. To copy the library files in the good directory run the 'GetLib.BAT' file. - The example compilation requires the use of YOUR C++ COMPILER you should be able to use without my advices. The DEMOLIFT example ==================== ** Presentation ** This example simulates the behavior of a lift cabin. At the beginning of its execution, the program let the user choose some configuration details (number of floors, size of the memory used to store the pending calls, gestion mode og this memory). The user acts through a command menu proposing the 6 folowing options: - 1 : Calling (used to call the lift) - 2 : Reparing (used to repare the lift when it powering system is out of order) - 3 : signal floor (used to simulate the action of the captors located at the different floors) - 4 : signal timer (used to simlate the end of a timer that pilots the closing of the door) - 5 : audit (allows to access to the internal state of the system components) - 6 : Quit (no comments) At creation time, the user can choose the type of behavior the memory storing the lift call should have. The choice is between: - a LIFO behavior (which is not the best choice for a lift), - a FIFO behavior (wich is usually correct). The way the two 'specialised' type of memories have been developped (by redefining part of the behavior described in the 'AbstractMemory' class shows the power of combining states and frozen methods). WARNING: Some 'bugs' have deliberately been left into the program so that the efficiency of the object behavior control can be proved. Amongs these bugs are: - any attemp to call the lift when its door is open will trigger an execution error as this induces a transition to incompatible states (door open and lift moving). - any sequence of calls that contains two time the same floor (like 1-2-1) will triggers an execution error the second time the same floor is served. The reason being that the button associated with the floor has already be switched off the first time the lift has stopped at the floor. For more accurate information concerning the classes used in this example please refer to the documentation provided with the 'Demo Disk'. ** The example source files ** The DEMOLIFTT example source file are: - the files with extension ".EHP" and ".ECP", - the 'ITEM.H' and 'ITEM.C' files. ** Translation/compilation of the example ** Same process than for the DEMODOC example except that you should look for 'DEMOLIFT' files and directories instead of 'DEMODOC'. /6/ - The speed test -------------- If you select the proper option while installing, you will find a 'SPEEDTST' sub-directory under the main installation directory. The SPEEDTST' directory contains almost the same files that the 'DEMOLIFT' directory. The purpose of this directory is to enable the user to effectively assertain the runtime over-head induced by the use of states and pre/post conditions in order to monitor at run-time the object behaviors. The 'MAINFILE.ECP' has been changed so that the program does not any more allow the user to drive the lift but forces the lift to move repeatedly between the ground floor and the first floor. The number of iterations is given by the user. Three '.BAT' files make it possible to generate three versions of the program: - the FULLTST version that implements all the behavior controls, - the LIGHT version that only checks the preconditions (i.e. 'are the requested methods allowed in the object current state'), - the PURE version that performs NO control. Each of the '.BAT' file ('FULLTST.BAT', 'LIGHT.BAT' and 'PURE.BAT') generates an '.EXE' file with the same root name ('FULLTST.EXE', 'LIGHT.EXE' and 'PURE.EXE'). You must this time update three 'makefiles' ('makefile.pur', 'makefile.lgh' and 'makefile.ful'). 7 - Future of the OOPS Toolset -------------------------- Two major changes should occur in the OOPS Toolset: - The tools of the current version (i.e. the textual translators) are going to be redevopped using the 'PCCTS' compiler generator toolset. Doing this should allow to improve the reliability of the translaters and to use a more 'upto date' version of the C++ grammar (i.e. supporting the exceptions and the templates). - A new set of tools should be added in order to support the graphical description of the object expected behavior and then to automatically generate the ".EHP" files.